{smcl}
{* 07jul2006}{...}
{cmd:help mata mm_nrroot()}
{hline}

{title:Title}

{p 4 19 2}
{bf:mm_nrroot() -- Newton-Raphson univariate zero (root) finder}


{title:Syntax}

{p 8 21 2}{it:rc} = {cmd:mm_nrroot(}{it:x}{cmd:,} {it:fdf}
[{cmd:,} {it:tol}{cmd:,} {it:itr}{cmd:,}
{it:...}]{cmd:)}

{pstd}
where

{p 11 16 2}
{it:rc}:  the return code; {it:rc}!=0 indicates that
no valid solution has been found

{p 12 16 2}
{it:x}:  {it:real scalar} containing initial guess; {it:x} will be replaced
by a {it:real scalar} containing solution

{p 10 16 2}
{it:fdf}:  {it:pointer scalar} containing address of function
supplying the function value and the first derivative; usually
this is coded {cmd:&}{it:funcname}{cmd:()}

{p 10 16 2}
{it:tol}:  {it:real scalar} specifying acceptable tolerance for the root
estimate (default is {it:tol}=0 to find the root as
accurate as possible)

{p 10 16 2}
{it:itr}:  {it:real scalar} specifying the maximum number of
iterations (default is {it:itr}=1000)

{p 10 16 2}
{it:...}:  up to 10 additional arguments to pass on to function {it:fdf}


{title:Description}

{pstd}{cmd:mm_nrroot()} uses the Newton-Raphson method to search
for the root of a function with respect to its first argument.
That is, {cmd:mm_nrroot()} approximates the value {it:x} for which
the function evaluates to zero. The
accuracy of the approximation is 4e+4*epsilon({it:x}) + {it:tol}.

{pstd}{cmd:mm_nrroot()} stores the found solution in {it:x} and issues
return code {it:rc}. Possible return codes are:

{phang2}{bind: 0:} everything went well

{phang2}{bind: 1:} convergence has not been reached within the
maximum number of iterations; {it:x} will contain the current approximation

{pstd}
{cmd:mm_nrroot()} is based on the example given in Press et
al. (1992:365-366).


{title:Remarks}

{pstd}Example:

        {com}: function myfunc(x, a) {c -(}
        >         fn = x^2 - a
        >         df = 2*x
        >         return(fn, df)
        > {c )-}

        : a = 2/3
        {res}
        {com}: mm_nrroot(x=1, &myfunc(), 0, 1000, a)
        {res}  0

        {com}: x
        {res}  .8164965809

        {com}: mm_nrroot(x=1, &myfunc(), 0.01, 1000, a)
        {res}  0

        {com}: x
        {res}  .8164965986

        {com}: sqrt(a)
        {res}  .8164965809{txt}


{title:Conformability}

{pstd}
{cmd:mm_nrroot(}{it:x}{cmd:,} {it:fdf}{cmd:,}
{it:tol}{cmd:,} {it:itr}{cmd:,} {it:...}{cmd:)}:{p_end}
           {it:x}:  1 {it:x} 1
         {it:fdf}:  1 {it:x} 1
         {it:tol}:  1 {it:x} 1
         {it:itr}:  1 {it:x} 1
         {it:...}:  (depending on function {it:fdf})
      {it:result}:  1 {it:x} 1


{title:Diagnostics}

{pstd}{it:x} will be set to missing if the function value or the
derivative evaluates to
missing at some point in the algorithm.


{title:Source code}

{pstd}
{help moremata_source##mm_nrroot:mm_nrroot.mata}


{title:References}

{phang}
Press, William H.,
Saul A. Teukolsky,
William T. Vetterling,
Brian P. Flannery (1992). Numerical Recipes in C. The Art of Scientific
Computing. Second Edition. Cambridge University Press.
{browse "http://www.numerical-recipes.com/"}


{title:Author}

{pstd} Ben Jann, University of Bern, jann@soz.unibe.ch


{title:Also see}

{psee}
Online:  help for
{bf:{help mf_mm_root:mm_root()}},
{bf:{help m2_ftof:[M-2] ftof}},
{bf:{help moremata}}
